home *** CD-ROM | disk | FTP | other *** search
- NETHACK.DOC
- How the networker really works
-
- Hue, Jr.
- (rewritten for STadel by Orc)
-
- This document provides a Utopian view of the Citadel auto
- networking protocol -- it ignores possible foulup points, and
- generally assumes that the gremlins of the world don't exist, and
- are gonadless in any case. Irrelevant complexities and gremlins
- are covered in following sections.
-
- 1) AN OVERVIEW OF A TYPICAL SESSION
-
- [make the call]
- |
- [identify network mode]
- |
- [identify caller]
- |
- [select options]
- |
- +---------------------> + <----------------+
- | | |
- | [send a command] |
- | / \ |
- +-- [accepted, process] [refused] -------+
- .
- .
- [become slave if rolereverse command]
- [hangup if hangup command]
-
- 2) IDENTIFYING NETWORK CALLERS
-
- This is how the master tells the slave that it's actually a
- network caller with a minimum of fuss and bother.
-
-
- master | slave
- ------ | -----
- Systems detect carrier
- |
- Send following 3 bytes: | If a <7> byte is received,
- 7 | look for the following 2
- 13 | bytes:
- 69 | 13
- and wait 4 seconds. | 69
- If have not received a | If these bytes are received,
- correct response (see | send back the following:
- slave column), then | ~7
- resend the above 3 bytes. | ~13
- This looping process should | ~69
- only be repeated 20 times. | And then wait for an ACK. If
- If, on the 20th try, still | one isn't received in 5 seconds,
- have not received a correct | return to what the system was
- response, HANGUP. | doing before it detected carrier.
- If have received a correct |
- response, send an ACK. |
- |
-
- So, essentially, the master waits a second, and then sends a 3
- byte sequence to the slave. When the slave receives those 3
- bytes successfully, it replies with the logical negation of those
- 3 bytes. The master then sends an ACK back, indicating that the
- call is stabilized. If 20 times the protocol fails, then the
- master hangs up, assuming something was wrong.
-
-
- 2.1) CALLER IDENTIFIES ITSELF
-
-
- After determining that this is really* a network call, both the
- master and the slave will drop into Xmodem for passing data back
- and forth. Therefore, the next byte originates with the slave,
- and that byte is the startup NAK. The master sends, in this
- order, nodeid, nodename, and the password (if any) it needs to get
- access to the other system.
-
- nodeid, nodename, password: Are normal null-terminated C strings.
-
- So, for example, let's say that a system using the nodename
- "buffalo" and with a nodeId of "US 612 477 0927" called some other
- system. After the call was stabilised, buffalo would send an
- identification packet like this to the other system:
-
- Id name
- US 612 477 0927<0>Buffalo<0><0>[nulls]
-
- If `Buffalo' is calling a system that needs the password
- `Gloopza', the slave's buffer would look like this
-
- ID name password
- US 612 477 0927<0>Buffalo<0>Gloopza<0>[nulls]
-
- 2.2) COMMAND REQUESTS
-
- So, what happens next? It's a loop, in which the master tells
- the slave that he wants to do thus-and-so, the slave responds
- with either "Fine, let's get on with it," or "Nope, [reason]".
-
- In more detail, it looks like this. First, remember that all
- communication is via Xmodem. A 'complete' command is a 1-byte
- command followed by 0 to 4 null terminated strings, followed by a
- null byte. Currently, the strings can only be 19 characters long.
- So, for instance, if we were to send only a single byte command,
- the sector received by the slave would look like this:
-
- <command-byte><0>[rest of sector, irrelevant]
-
- A command that also needs to send, say, two strings to the slave
- would look like this:
-
- <command-byte><string1><string2><0>[rest of sector, irrelevant]
-
- Where string1 and string2 are null-terminated. These nulls (for
- the strings) should not* be mistaken for the end of command null!
-
- So, the slave has received the command. At this point, the slave
- must decide if he wants to (or can) execute the command requested
- by the master. If he can, he just sends back (via WC) one byte,
- called GOOD, and then does what the command implies is next.
-
- If, for any number of reasons, he can't, he should then send back
- one byte, called BAD, and a null-terminated string (< 126
- characters) that is simply text that tells the master why he can't
- execute, e.g., facility not supported, this room doesn't exist,
- etc. If BAD is sent back, then the master does the next thing on
- his list of things to do.
-
- BAD and GOOD are the boolean values FALSE and TRUE, respectively.
- If the reply byte is nonzero, it implies a GOOD response.
-
- 2.3) NET MESSAGE FORMAT
-
- The format for all messages on the net consists of a collection
- of C strings (text followed by a null) that represents all the
- data associated each message. Each field is identified by the
- first character of text in that field, and each identifier is
- unique. The fields may come in any order, with the exception that
- the Message text itself is the last field. Any data following the
- null byte that ends the Message field is assumed to be part of the
- next message, or the almost inevitable garbage that occurs in the
- last sector of a WC transfer.
-
- All data is straight ASCII, ended with a null byte, including
- those fields that could* be encoded in binary.
-
- The following fields and identifiers are currently supported.
-
- Identifier Data Max Length
- ---------- ---- ----------
- 'A' Author of current message. 125
- 'D' Date on which message was written. 19
- 'I' #organization string for the system 39
- where this message originated.
- 'N' Name of system which message was 9*
- written on.
- 'O' ID of system which message was written 19
- on (i.e., "US 612 866 1804").
- 'R' Room which message was originally 19
- written in.
- 'T' Recipient of message (normally for 125
- private Mail).
- 'C' Time message was written. 19
- 'J' Subject of message. 79
- '#' Usenet-style message-ID 79
- 'M' Message text. 9999
- 'Z' Network routing code, in the form 21
- @<sigchar><message-id of routing system>
-
- ----------
- * This field is actually 19 characters, but it is recommended to
- only use the first 9.
-
- So, a message on Pell (nodeId US 504 588 1258, nodeName `Pell',
- organization ` (what's all this then?)') that looks like this:
-
- 86Feb01 @ 10:01 from Guido in Q>
- This is a test.
-
- would look like this when being sent across the net:
-
- D86Feb01<0>C10:01<0>NPell<0>Iwhat's all this then?<0>
- OUS5045881258<0>AGuido<0>RQ<0>Z@LUS5045881258<0>
- MThis is a test<LF><0>
-
- 2.4) ROOMSHARING
-
- Citadel nodes network by sharing one or more rooms. Any Citadel
- node can choose to keep an image of any public room on any other
- Citadel node (subject to willingness to foot the phone bills, of
- course!). The procedure in essence simply involves calling the
- imaged node up periodically and copying any new messages in the
- imaged room into the local image.
-
- Complexities arise primarily from the possibility of densely
- connected networks: one does not wish to accumulate multiple
- copies of a given message, which can easily happen. Nor does one
- want to see old messages percolating indefinitely through the
- system.
-
- STadel 3.3a uses the following `brute-force' method of ensuring
- that this problem doesn't occur: Each networking system will have
- a file containing the date of the most recent message from every
- system that shares a given room. If messages come into this room
- that are older than the date of the last message, they will be
- rejected.
-
- 3) CURRENTLY SUPPORTED FACILITIES
-
- HANGUP<0>: This command is a simple 1-byte command that tells
- the slave to hang up. Upon receipt, the slave doesn't bother
- with replying to the master -- he just hangs up. Obviously, the
- master should have completed all other commands by now.
-
- HANGUP ->
- <- (slave hangs up)
-
-
- MAIL <1>: This is simply a request for the slave to accept for
- delivery to users on the slave's system of mail from the master.
-
- MAIL ->
- <- reply GOOD
- mail ->
-
-
- RECEIVE_SHARED_ROOMS <5>: Send new netmessages to the other
- system. This command will be rejected if both systems do not have
- the room and aren't both sharing it with the other system. The
- format of the command is
-
- <RECEIVE_SHARED_ROOMS>room<0>....
-
- and it is followed by a single file that contains all the new
- shared messages for the room in question. The messages in this
- file are in the usual network message format and are separated by
- $FF characters (i.e; <message>$FF<message>$FF<message>...) The
- receiving system leaves the messages alone, except for the Z
- field, which is converted to Z@H<nodeid> if the master has this
- room set up as a backbone with the callee, and Z@L<nodeid>
- otherwise.
-
- The slave determines what to send in the following way: All
- messages that originated on the slaves' system are sent, as well
- as all messages that have a Z@H field on the master's system. If
- the slave has set the room up as a backbone with the master, all
- Z@L messages will be sent as well.
-
-
- CHECK_MAIL <6>: This command requests that STadel checks to see
- if all the netmail that was sent this session is valid. The
- slave will check all the mail that came in and send back a single
- file containing info for each piece of mail that could not be
- delivered. The file consists of (surprise!) null-terminated
- strings set up like
-
- <reason-char>author<0>dest<0>date @ time<0>
-
- The reason-char can be 1 (no such person/system found) or 2 (no
- recipient?). Any other failure and the reason-char will be set to
- 99.
-
- If all the mail was correctly addressed, a null file will be
- returned.
-
-
- SEND_FILE <7>: This command sends a file to the slave, provided
- the slave has enough room in its' network receipt directory. The
- format of the command is
-
- <SEND_FILE>filename<0>junk<0>size<0>...
-
- IF the command is accepted, the file is sent.
-
- SEND_FILE file ->
- <- reply GOOD
- file ->
-
-
- OPTIONS <11>: Tell the slave what options the master supports.
- The slave will reply GOOD if it supports those options. The
- format of the options command is:
-
- <OPTIONS>options<0>...
-
- OPTIONS<opt> ->
- <- reply GOOD<opt-supported>
- ... networking continues via
- ... new protocol
-
- The reply is not a normal GOOD reply, because the slave will pass
- back the list of options supported.
-
- The following characters are defined for the options:
- y - Use Ymodem for networking
- w - Use WXmodem for networking
- k - Use Kermit for networking
- z - Use Zmodem for networking
- c - compress things before transferring them.
-
- For example, if a system that supports wxmodem and ymodem calls a
- system that only supports ymodem, the exchange would be like so:
-
- OPTIONS<wy> ->
- <- reply GOOD<y>
- ... networking continues via
- ... ymodem.
-
- The standard format for the options string is
- <proto-list>[,<modifiers>]. If, for instance, your system wanted
- to network in wxmodem or ymodem, plus it supports compressed
- transfers, it would send an option string of <wy,c> to the
- receiver. If the receiver can handle compression, it would
- return <y,c>.
-
-
- BATCH_REQUEST <13>: Request files from the slave. This command
- asks for files from a specified room on the slave. The format of
- the command is:
-
- <BATCH_REQUEST>room<0>filespec<0>[nulls]
-
- If the command is accepted, the files are sent back immediately
- via `ymodem batch' form (header block, then file, null header to
- terminate.) The header block contains the filename
- (null-terminated) and the size of the file in bytes (ascii string,
- null terminated)
-
- BATCH_REQUEST ->
- <- GOOD
- <- header0
- <- file0
- <- header1
- <- file1
- .
- .
- .
- <- [null]
-
- Note that the transfer protocol used will be whatever protocol is
- active at this time. If the protocol being used has an alternate
- way to do file batching (zmodem, kermit), that will be used
- instead of the ymodem form.
-
-
- ROLE_REVERSE <201>: Reverse master/slave roles so that the slave
- may do its half of the networking. This may only be done once,
- because of citadel-86 restrictions. If the slave doesn't want to
- role-reverse, it will hang up the phone on the master.
-
- ROLE_REVERSE ->
- <- reply GOOD
- <- commands
-
-
- Two other command bytes are reserved for future use:
-
- BATCH_SEND<12>: Send files to slave via ymodem batch
- REMOTE_CMD<10>: execute a command remotely, return output via WC
-
-